Skip to content

docs: codify subagent-mediated API / library / platform research workflow#397

Merged
H-Chris233 merged 1 commit intobetafrom
docs/research-first-subagent-mechanism
May 10, 2026
Merged

docs: codify subagent-mediated API / library / platform research workflow#397
H-Chris233 merged 1 commit intobetafrom
docs/research-first-subagent-mechanism

Conversation

@appergb
Copy link
Copy Markdown
Collaborator

@appergb appergb commented May 10, 2026 •
edited by github-actions Bot
Loading

User description

Why

User-requested via `/init`：编码外部依赖时，Claude 必须先派子 agent 去查实时文档，不能基于训练记忆瞎写。机制要在 .md 里固化，否则下一会话会丢。

发现：origin/beta 的 AGENTS.md 实际没有这段（我读 local 看到的是脏未追踪状态），所以这个 PR 等于首次落地这条规则到 repo。

What

1. AGENTS.md +24 行

新增 `### Third-party service integrations & library / platform API research` 段，覆盖：

  • 触发范围：HTTP API（ASR / LLM / GitHub / Tauri plugin）、Rust crate / npm 包、平台 API（Apple Security framework / Win32 / CoreFoundation / Carbon / AppKit）、lock 文件锁的版本特性
  • 5 步研究流程：分析 → 派子 agent 拉文档 → 过滤结果 → cross-verify 一项关键事实 → 写代码
  • 子 agent prompt 必备结构：单服务单 agent；优先官方文档域名；强制结构化返回（endpoint / schema / 错误码 / 版本号）
  • 4 条反模式：凭记忆写、贴整页文档、混 API 版本、跳过错误处理

2. CLAUDE.md +52 行

Claude-specific 落地：

  • 触发条件 / 不需要派子 agent 的情况（避免过度调用）
  • 工具优先级：Context7 MCP > documentation-lookup skill > Agent dispatch > 单点 WebFetch
  • 子 agent prompt 必备 4 字段（目标 / 仓库现状 / 必返结构 / 禁令）
  • 5 条反例

CLAUDE.md 段头明确 link 回 AGENTS.md，避免规则两边漂移。

Test plan

  • 纯 docs，无代码；不影响 CI 任何 platform build
  • CI green
  • pr_agent advisory（这种 docs PR 通常 No major issues）

PR Type

Documentation

Description

  • Codify mandatory research-before-coding workflow in AGENTS.md

  • Define sub-agent dispatch guidelines and anti-patterns

  • Add Claude-specific tooling guidance and prompt structure in CLAUDE.md

Diagram Walkthrough

flowchart LR
  A["External dependency needed"] --> B["Analyze external calls"]
  B --> C["Dispatch sub-agent"]
  C --> D["Filter & cross-verify"]
  D --> E["Implement from verified docs"]
Loading

File Walkthrough
Relevant files
Documentation
AGENTS.md
Codify mandatory research workflow for external integrations

AGENTS.md

  • New section: Third-party service integrations & library / platform API
    research
  • 5-step research-first workflow (analyze, delegate, filter,
    cross-verify, implement)
  • Sub-agent search brief with structured-result requirements
  • Four anti-patterns (writing from memory, pasting entire docs, mixing
    API versions, skipping error handling)
 +24/-0   
CLAUDE.md
Add Claude-specific tool guidance for research workflow   

CLAUDE.md

  • New Claude-specific section linking to AGENTS.md workflow
  • Trigger conditions for when sub-agent dispatch is required
  • Tool priority: Context7 MCP → documentation-lookup skill → Agent
    dispatch → direct WebFetch
  • Required sub-agent prompt fields and expanded anti-patterns
 +52/-0   

docs: codify subagent-mediated API research workflow
0cc3a24 
User-requested mechanism (/init args): when implementing against any
external surface — third-party HTTP APIs, unfamiliar Rust crates / npm
packages, or platform APIs (Apple Security framework / Win32 / Carbon
/ AppKit) — Claude must dispatch a dedicated subagent to fetch
authoritative documentation rather than write integration code from
training memory. The subagent acts as a network-search-and-retrieval
layer that returns distilled, version-aware usage data so the main
context stays uncluttered and the implementation always tracks the
current upstream surface.

Two surgical edits:

1. AGENTS.md §"Third-party service integrations" — heading widened to
   "Third-party service integrations & library / platform API research"
   so the existing 5-step research-first workflow explicitly covers
   library + platform APIs, not just HTTP service integrations.
   Rephrased the lead-in paragraph to enumerate the broader scope.

2. CLAUDE.md — new top-level section "调研先于编码：派子 agent 查 API
   / 库 / 平台文档" pointing back to AGENTS.md as the canonical rules
   and listing the concrete tooling Claude Code has available:
   Context7 MCP (resolve-library-id + query-docs), the
   documentation-lookup skill, and Agent dispatch with
   subagent_type=general-purpose. Specifies trigger conditions,
   non-trigger conditions (when grep is enough), the prompt fields
   every subagent dispatch must include, and the four canonical
   anti-patterns.

No code changes; pure docs.
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 10, 2026

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ No major issues detected

@appergb
Copy link
Copy Markdown
Collaborator Author

appergb commented May 10, 2026

该部分文档用于帮助项目内其他 AI 编程工作者进行 AI 编程的排布，以有效提升其他项目工作者的工作能力和计划执行力。

@H-Chris233 H-Chris233 merged commit 69081e0 into beta May 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@H-Chris233 H-Chris233 H-Chris233 approved these changes

Assignees

No one assigned

Labels

Review effort 1/5

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@appergb @H-Chris233